export const metadata = {
  title: 'Python SDK',
  description:
    'Reference documentation for the Surfer Protocol Python SDK.',
}

# Python SDK

The Surfer Protocol Python SDK provides a simple interface to interact with the Surfer-Data desktop application.

## Prerequisites

1. **Desktop Application**: The Surfer desktop application must be running in the background for the SDK to work.
   - Follow the installation instructions on the [Desktop Application Installation](/desktop/installation) page
   - Connect your platforms and export your data to use with the SDK.

> Note: The desktop app runs a local server on port 2024 that the SDK communicates with. Make sure the server is running before using the SDK.

## Installation

<CodeGroup>

```bash
pip install surfer-protocol
```

</CodeGroup>

## Quick Start

<CodeGroup>

```python
from surfer_protocol import SurferClient

# Initialize the client
client = SurferClient()

# Get data for a specific platform
data = client.get("bookmarks-001")

# Export data for a platform
export_result = client.export("bookmarks-001")
```

</CodeGroup>

## API Reference

### SurferClient

The main client class for interacting with the Surfer Protocol desktop application.

```python
from surfer_protocol import SurferClient

client = SurferClient()
```

### Methods

#### `get(platform_id: str) -> dict`
Retrieves the most recent data for a specific platform.

```python
# Get Twitter bookmarks
bookmarks = client.get("bookmarks-001")

# Get Gmail data
emails = client.get("gmail-001")

# Get iMessage data
messages = client.get("imessage-001")
```

#### `export(platform_id: str) -> dict`
Triggers a new export for a specific platform.

```python
export_result = client.export("bookmarks-001")
```

## Platform IDs

The following platform IDs are currently supported:
- `bookmarks-001`: Twitter bookmarks
- `gmail-001`: Gmail messages
- `imessage-001`: iMessage conversations
- `connections-001`: LinkedIn connections
- `notion-001`: Notion workspace
- `chatgpt-001`: ChatGPT history

## Response Schemas

All API responses follow a standard format:

```python
{
    "company": str,        # Company name
    "name": str,          # Platform name
    "runID": str,        # Unique export identifier
    "timestamp": int,    # Unix timestamp of export
    "content": List[Dict] # Platform-specific data
}
```

> To view the full schema for each platform, see the [platforms page](/desktop/platforms) and choose the platform you're interested in.

## Example Applications

Check out our [Cookbook](/cookbook/python) for example applications built with Surfer Protocol.

## Error Handling

The SDK includes built-in error handling for common scenarios:

```python
try:
    client = SurferClient()
    data = client.get("bookmarks-001")
except ConnectionError as e:
    print("Failed to connect to Surfer desktop app. Is it running?")
except Exception as e:
    print(f"An unexpected error occurred: {e}")
```

## Best Practices

1. **Connection Management**: The client automatically manages the connection and cleans up resources when destroyed.
2. **Error Handling**: Always wrap API calls in try-except blocks to handle potential connection issues.
3. **Resource Efficiency**: Reuse the same client instance for multiple operations instead of creating new instances.
